Plugin Overview

HouseBot X10 Device Plugin Overview

The HouseBot X10 Device Plugin supports the following three X10 Devices.

  1. X10 Transmitter
  2. X10 Lamp and Appliance Modules
  3. X10 Controller

All of these Devices require a Hardware Interface that supports sending or receiving X10 signals over the power line.

Although there are many other types of X10 devices, they all use the same X10 Protocol. X10 devices are either transmitters, receivers, or both. Transmitters are devices that will generate and send X10 commands over the power line. Receivers are devices that receive X10 commands over the power line. Some devices can both send and receive X10 Commands.

All three of the Devices use the same X10 concepts and communicate using the same X10 protocol. For a brief overview of the protocol, see Overview of X10.

HouseBot uses Properties and Property Values to represent the different X10 settings and functions. This allows the physical device to be controlled by simply changing Property Values on the HouseBot Device. For example, to turn on an X10 light, the Power State Property for the light is changed to On. This will cause the underlying Hardware Interface to send the appropriate X10 commands to turn the light on. By abstracting the X10 protocol, commands, and device capabilities into the HouseBot Device, the user does not need to understand much about X10 at all.


Overview of X10

X10 is a communication protocol for sending and receiving commands over the AC power line. X10 has been around for many years and has evolved into an inexpensive and semi-reliable method for home automation.

There are a wide variety of hardware devices that use the X10 protocol. Generally though, all devices fall into two categories; either transmitters or receivers (or both).

Transmitters are devices which will send commands over the power line. An example of a transmitter is an X10 switch on a wall. The switch could be used to turn on an X10 light. The switch (transmitter) would send a command to the light (receiver) to turn it on or off.

Receivers are the most common X10 devices on the market. They consist of hardware that is to be controlled by X10. Examples of some common X10 receivers are:

  • Appliance Module: Controls electrical appliances, stereo, TV, Hot Water Tank, Hot Tub etc.
  • Lamp Module: Turn lamps ON/OFF and DIM/BRIGHT
  • Wall Switch: Turn lights on the existing circuit ON/OFF and DIM/BRIGHT. 3 way switches also available.
  • Wall Receptacle: Control whatever is plugged into the outlet ON/OFF and DIM/BRIGHT.
  • Universal Module: Control low voltage systems such as sprinkler valves, drapery controls, garage door opener etc.
  • Chime Module: Chimes when ON signal received.

X10 devices are identified on the power line by unique addresses. The address is necessary so when an X10 command is sent, the intended hardware will respond to the command and all other X10 devices will ignore the command. The X10 address comprises a House Code and a Unit Code. By using House codes and Unit codes, up to 256 unique addresses can be controlled.

House Codes can rage in values from A to P. The House Code defines the basic group that the device belongs to. All devices have a House Code value whether they are managed as a group or not. Grouping devices by House Codes allows all of the devices in the group to be controlled together with a single command.

Unit Codes can range in values from 1 to 16. The Unit code further defines the device's address and is used with the House Code to uniquely identify a single device on the power line. Devices can share the same House Code and Unit Code allowing them to be controlled together as the same device.

Once the device address (House Code and Unit Code) have been setup, Commands can be sent from one device to one or more other devices. The X10 command set is very simple. The most common X10 commands are:

  • ON: Instructs the device to turn On.
  • OFF: Instructs the device to turn Off.
  • DIM: Instructs the device to increase its lighting level by one increment. (*)
  • BRIGHT: Instructs the device to decrease its lighting level by one increment (*)
  • ALL LIGHTS ON: Instructs all devices to turn On.
  • ALL LIGHTS OFF: Instructs all devices to turn Off.

(*) This command is not supported by all X10 devices.

There are many good X10 resources on the Internet. The following links provide more detail on X10.

  • X10's Overview
  • HomeToys articles


Transmitter

The HouseBot X10 Transmitter Device is used to monitor and control ANY X10 transmitter device. There are a wide variety of specialized X10 devices that are classified as transmitters. Transmitters are devices that send X10 commands on the AC power line to another X10 device. In effect, the HouseBot Transmitter Device will mirror the Power State of the physical device. If the physical device sends an ON command, the HouseBot Device will change its Power State Property Value to On.

Note:

  • The 'Transmitter' term is somewhat confusing, since the physical device that HouseBot is representing with its 'Transmitter' Device is technically called a transmitter. However, the HouseBot device actually receives the commands sent by the transmitter device in order to hold the correct Power State of the physical device.

The HouseBot X10 Transmitter Device functions not only as a mirror of the physical devices Power State, but it also can change the Power State of the device making it a true 2-way X10 device.

The X10 Transmitter Device has the following Properties.

Property | Description
X10 House Code | Specifies the X10 House Code of the physical device to mirror. Valid values are A through P.
X10 Unit Code | Specifies the X10 Unit Code of the physical device to mirror. Valid values are 1 through 16.
Power State | Specifies the current Power State (Off or On) of the last command that was sent by the device. If the transmitter sends an ON command, the Power State Property Value will automatically change to On. This Property can also be used to change the current Power State of the transmitter by sending an X10 command to the physical device. Note: Sending an X10 command is only valid if the device supports 2-way X10 (both sending and receiving commands).

Sample Use:

The following sample helps illustrate how a HouseBot X10 Transmitter Device is used.

Application: A table top X10 controller (such as the CP290) is used to turn off all of the lights and media equipment at night.

Usage:

  1. Configure the CP290 to use House Code P.
  2. In HouseBot, create a Transmitter Device and assign it House Code P and Unit Code 1.
    1. From the HouseBot main menu, select "File / New / Device...".
    2. The New Device Wizard will prompt you through the setup.
    3. Select the "Requires Hardware Interface" radio button.
    4. Select a Hardware Interface that supports X10.
    5. Select the "X10 Transmitter" hardware device.
    6. Give a unique and descriptive name such as "Evening All Off".
    7. Set the X10 House Code Property to P.
    8. Set the X10 Unit Code Property to 1.
  3. Create a Task to turn off the lights and media equipment. Note: The lights and media equipment must also be controlled by HouseBot, but they can be controlled by ANY protocol, not just X10. For more information on creating Tasks, see the main HouseBot on-line help.

    When creating the Task, have the condition that executes the Task trigger off of the "Evening All Off" Power State Property and test whether it is Off. The condition test for this example would be if ('Evening All Off' is Equal 'Off') Then

  4. Now when the P1 button on the CP290 is pressed for Off, the Task will execute and turn off all lights and media equipment.


Receiver

Lamp and Appliance Modules (Receivers)

The HouseBot X10 Lamp and Appliance Modules can be used to control almost any X10 receiver device. It is not limited to physical Lamp and Appliance modules only. Receivers are devices that are controlled by HouseBot or other X10 controllers. Some common examples of X10 devices that can be controlled with the Lamp Module Device are

  • Appliance Module: Controls electrical appliances, stereo, TV, Hot Water Tank, Hot Tub etc.
  • Lamp Module: Turn lamps ON/OFF and DIM/BRIGHT
  • Wall Switch: Turn lights on the existing circuit ON/OFF and DIM/BRIGHT. 3 way switches also available.
  • Wall Receptacle: Control whatever is plugged into the outlet ON/OFF and DIM/BRIGHT.
  • Universal Module: Control low voltage systems such as sprinkler valves, drapery controls, garage door opener etc.
  • Chime Module: Chimes when ON signal received.

The X10 Lamp and Appliance Devices have the following Properties.

Property | Description
X10 House Code | Specifies the X10 House Code of the physical device to mirror. Valid values are A through P.
X10 Unit Code | Specifies the X10 Unit Code of the physical device to mirror. Valid values are 1 through 16.
Power State | Specifies the current Power State (Off or On) of the device. Changing the value of this Property will cause the physical device that is assigned to the House Code and Unit Code specified to also change states. Therefore, to turn an X10 Lamp on, simply change the value to On.
Direct X10 Command | This Property can be used to send an X10 command to the X10 device. It can send any X10 command, but is generally useful for sending Dim and Bright commands. The Property format is a composite format that consists of the command and any additional parameters. For a full list of commands, see the Controller help section. The composite format is slightly different from the Controller Device in that it does NOT include the House Code and Unit Code.
Leviton Dim Level | Leviton X10 devices support 100 levels of dimming. Valid values for this Property are numeric values from 0 to 100. If the value is set to 0, the Power State Property is changed to Off. If the value is set to a value other than 0, the Power State Property is changed to On. Note: Not all Hardware Interfaces support the Leviton Dim functionality. This Property is only available on X10 Lamp Devices.
X10 Preset Dim Level | Some brands of X10 devices support 32 levels of dimming using the X10 preset commands. Valid values for this Property are numeric values from 0 to 31. If the value is set to 0, the Power State Property is changed to Off. If the value is set to a value other than 0, the Power State Property is changed to On. Note: Not all Hardware Interfaces support the Preset Dim functionality. This Property is only available on X10 Lamp Devices.

Notes:

  • The X10 Lamp Module Device operates as a 2-way device. If an X10 command is detected on the power line for the Device address, HouseBot will change the Power State property value to match the value received.
  • The HouseBot Lamp Module does not support X10 DIM and BRIGHT commands. This is largely due to the fact that the X10 protocol implementation of these commands has been better served by newer dimming implementations. The Leviton Dim and Preset Dim functions are the suggested methods for controlling the Dim state of an X10 device.


Controller

The HouseBot X10 Controller can be used to monitor and control any X10 device. It provides a low-level method of monitoring and controlling X10 devices that is not possible with the Transmitter and Lamp Module Devices. The Controller Devices does not directly map to any specific X10 physical device. Instead, it provides an overall view and control of all X10 power line traffic.

The X10 Controller Device has the following Properties.

Property | Description
Composite Property | This property reflects the last X10 command received on the power line. It can also be used to send X10 commands to any physical device. The format of the Property Value is H;U[;C[;L | R]]. Where H=House Code, U=Unit Code, C=Command, L=Leviton Dim level (*), R=Repeat count (*). For examples of the format, see the table below. (*) Leviton Dim is only valid for the Leviton Dim command. Repeat count is only valid for the Dim, Bright, Preset Dim 1 and Preset Dim 2 commands.

Commands

The following commands are supported, although some are read-only.

All Units Off, All Lights On, On, Off, Dim, Bright, All Lights Off, Extended Code, Hail Request, Hail Ack, Preset Dim 0, Extended Data, Status On, Status Off, Status Request, Preset Dim 1, Leviton Dim

Command Format Examples

The following table gives some examples of the command format.

Command | Description
A;1;On | Turn on device at House Code A and Unit Code 1
P;1;Leviton Dim;50 | Turn device at House Code P and Unit Code 1 to half brightness (assuming the device supports Leviton Dim)
B;*;All Lights Off | Turn off all devices that have their House Code set to B
P;1;Bright;5 | Increment the brightness by five steps of the device device at House Code P and Unit Code 1
P;5;Preset Dim 1;10 | Turn device at House Code P and Unit Code 5 to 1/3 brightness
P;5 | Send P5 with no command. Only used in special situations.

Tip:

  • Configure an X10 Controller and trace the Composite Property changes to a log file. This provides a historic log of all X10 traffic received by the system. It can be helpful when troubleshooting X10 anomalies.
  • If unsure of the format for a specific command to send, view the history of the Composite Property and the command may have already been received. The format for sending and receiving is the same.
  • Using a Controller can simplify configuration of the system when trying to control all devices in the same House Code.